
// A StatsTable is a table of statistics.  It can be used across multiple
// processes and threads, maintaining cheap statistics counters without
// locking.
//
// The goal is to make it very cheap and easy for developers to add
// counters to code, without having to build one-off utilities or mechanisms
// to track the counters, and also to allow a single "view" to display
// the contents of all counters.
//
// To achieve this, StatsTable creates a shared memory segment to store
// the data for the counters.  Upon creation, it has a specific size
// which governs the maximum number of counters and concurrent
// threads/processes which can use it.

#ifndef __base_stats_table_h__
#define __base_stats_table_h__

#pragma once

#include <hash_map>
#include <string>

#include "base/synchronization/lock.h"
#include "base/threading/thread_local_storage.h"

namespace base
{

    class StatsTable
    {
    public:
        // Create a new StatsTable.
        // If a StatsTable already exists with the specified name, this StatsTable
        // will use the same shared memory segment as the original.  Otherwise,
        // a new StatsTable is created and all counters are zeroed.
        //
        // name is the name of the StatsTable to use.
        //
        // max_threads is the maximum number of threads the table will support.
        // If the StatsTable already exists, this number is ignored.
        //
        // max_counters is the maximum number of counters the table will support.
        // If the StatsTable already exists, this number is ignored.
        StatsTable(const std::string& name, int max_threads, int max_counters);

        // Destroys the StatsTable.  When the last StatsTable is destroyed
        // (across all processes), the StatsTable is removed from disk.
        ~StatsTable();

        // For convenience, we create a static table.  This is generally
        // used automatically by the counters.
        static StatsTable* current() { return global_table_; }

        // Set the global table for use in this process.
        static void set_current(StatsTable* value) { global_table_ = value; }

        // Get the slot id for the calling thread. Returns 0 if no
        // slot is assigned.
        int GetSlot() const;

        // All threads that contribute data to the table must register with the
        // table first.  This function will set thread local storage for the
        // thread containing the location in the table where this thread will
        // write its counter data.
        //
        // name is just a debugging tag to label the thread, and it does not
        // need to be unique.  It will be truncated to kMaxThreadNameLength-1
        // characters.
        //
        // On success, returns the slot id for this thread.  On failure,
        // returns 0.
        int RegisterThread(const std::string& name);

        // Returns the number of threads currently registered.  This is really not
        // useful except for diagnostics and debugging.
        int CountThreadsRegistered() const;

        // Find a counter in the StatsTable.
        //
        // Returns an id for the counter which can be used to call GetLocation().
        // If the counter does not exist, attempts to create a row for the new
        // counter.  If there is no space in the table for the new counter,
        // returns 0.
        int FindCounter(const std::string& name);

        // TODO(mbelshe): implement RemoveCounter.

        // Gets the location of a particular value in the table based on
        // the counter id and slot id.
        int* GetLocation(int counter_id, int slot_id) const;

        // Gets the counter name at a particular row.  If the row is empty,
        // returns NULL.
        const char* GetRowName(int index) const;

        // Gets the sum of the values for a particular row.
        int GetRowValue(int index) const;

        // Gets the sum of the values for a particular row for a given pid.
        int GetRowValue(int index, int pid) const;

        // Gets the sum of the values for a particular counter.  If the counter
        // does not exist, creates the counter.
        int GetCounterValue(const std::string& name);

        // Gets the sum of the values for a particular counter for a given pid.
        // If the counter does not exist, creates the counter.
        int GetCounterValue(const std::string& name, int pid);

        // The maxinum number of counters/rows in the table.
        int GetMaxCounters() const;

        // The maxinum number of threads/columns in the table.
        int GetMaxThreads() const;

        // The maximum length (in characters) of a Thread's name including
        // null terminator, as stored in the shared memory.
        static const int kMaxThreadNameLength = 32;

        // The maximum length (in characters) of a Counter's name including
        // null terminator, as stored in the shared memory.
        static const int kMaxCounterNameLength = 64;

        // Convenience function to lookup a counter location for a
        // counter by name for the calling thread.  Will register
        // the thread if it is not already registered.
        static int* FindLocation(const char* name);

    private:
        class Private;
        struct TLSData;
        typedef stdext::hash_map<std::string, int> CountersMap;

        // Returns the space occupied by a thread in the table.  Generally used
        // if a thread terminates but the process continues.  This function
        // does not zero out the thread's counters.
        // Cannot be used inside a posix tls destructor.
        void UnregisterThread();

        // This variant expects the tls data to be passed in, so it is safe to
        // call from inside a posix tls destructor (see doc for pthread_key_create).
        void UnregisterThread(TLSData* tls_data);

        // The SlotReturnFunction is called at thread exit for each thread
        // which used the StatsTable.
        static void SlotReturnFunction(void* data);

        // Locates a free slot in the table.  Returns a number > 0 on success,
        // or 0 on failure.  The caller must hold the shared_memory lock when
        // calling this function.
        int FindEmptyThread() const;

        // Locates a counter in the table or finds an empty row.  Returns a
        // number > 0 on success, or 0 on failure.  The caller must hold the
        // shared_memory_lock when calling this function.
        int FindCounterOrEmptyRow(const std::string& name) const;

        // Internal function to add a counter to the StatsTable.  Assumes that
        // the counter does not already exist in the table.
        //
        // name is a unique identifier for this counter, and will be truncated
        // to kMaxCounterNameLength-1 characters.
        //
        // On success, returns the counter_id for the newly added counter.
        // On failure, returns 0.
        int AddCounter(const std::string& name);

        // Get the TLS data for the calling thread.  Returns NULL if none is
        // initialized.
        TLSData* GetTLSData() const;

        Private* impl_;

        // The counters_lock_ protects the counters_ hash table.
        Lock counters_lock_;

        // The counters_ hash map is an in-memory hash of the counters.
        // It is used for quick lookup of counters, but is cannot be used
        // as a substitute for what is in the shared memory.  Even though
        // we don't have a counter in our hash table, another process may
        // have created it.
        CountersMap counters_;
        ThreadLocalStorage::Slot tls_index_;

        static StatsTable* global_table_;

        DISALLOW_COPY_AND_ASSIGN(StatsTable);
    };

} //namespace base

#endif //__base_stats_table_h__